Shareware Overload Trio 2

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Overload Trio 2 / Shareware Overload Trio Volume 2 (Chestnut CD-ROM).ISO / dir39 / anidos.zip / ANIDOS.DOC < prev next >

Wrap

Text File | 1993-06-29 | 49KB | 1,284 lines

*************************************************************** * * * Program Title: DOS ANIMATOR V1.2 * * CompuServe Registration ID: 1046 * * Filename: ANIDOS.ZIP * * * * DEMONSTRATION VERSION * * Copyright (C) Matt Harvey, 1987-1993 * * All rights reserved * * * *************************************************************** This is a demonstration version of DOS ANIMATOR V1.2. It has restricted capabilities, see the appendix. To register and receive the latest full-featured version of DOS ANIMATOR, use the "Shareware Registration" forum on CompuServe. If you're not on CompuServe, fill in and return the registration form at the end of this document. You are free to pass copies of this software to others, providing it is supplied in its original, unmodified form (as file ANIDOS.ZIP), and no fee is charged for the software. This software was originally written to control a continuous running software demonstration at a large software exhibition, and has subsequently been used for automating the start-up to tedious DOS packages, accessing bulletin boards, and software testing. Recently I've used it to write a fancy Microsoft Windows "front end" for a huge old DOS package. The Windows program creates a DOS ANIMATOR script file, according to the operation, then invokes the DOS application (in an invisible window). The script file saves screen output and messages to a file, which is processed by the Windows front-end to determine the outcome of the action. This works fast, especially if a disk cache is used, and saved about 10 man-years of work in re-writing the old DOS package. Clever users of the Windows front-end can also write their own scripts, so that they can add their own "macros" to the Windows program. When it was orginally written (1987), there were no packages readily available that could do this job. There are now several similar products available, but they're very expensive - this one's cheap! ANIDOS CONTENTS ════════ Page 1. INTRODUCTION . . . . . . . . . . . . . . . . . 1 2. INSTALLATION ON A HARD DISK . . . . . . . . . 2 3. OPERATION . . . . . . . . . . . . . . . . . . 3 4. SCRIPT FILE STATEMENTS . . . . . . . . . . . . 5 4.1 Comments . . . . . . . . . . . . . . . . 5 4.2 Key strokes . . . . . . . . . . . . . . 5 4.3 Jump labels . . . . . . . . . . . . . . 5 4.4 Jumps . . . . . . . . . . . . . . . . . 6 4.5 Gosub and Return . . . . . . . . . . . . 6 4.6 Timing and delays . . . . . . . . . . . 6 4.7 Displaying pop-up windows . . . . . . . 7 4.8 Displaying texts . . . . . . . . . . . . 7 4.9 Interactive keyboard input . . . . . . . 8 4.10 Examining the screen . . . . . . . . . . 9 4.11 Shift, Alt, Ctrl and Lock key states . . 9 4.12 Cursor on/off . . . . . . . . . . . . . 10 4.13 File operations . . . . . . . . . . . . 10 4.13.1 Save . . . . . . . . . . . . . 10 4.13.2 File . . . . . . . . . . . . . 11 4.13.3 Unlink . . . . . . . . . . . . . 11 4.14 Quit, end script . . . . . . . . . . . . 11 5. SCRIPT LANGUAGE SUMMARY . . . . . . . . . . . 12 6. KEY CODE TABLE . . . . . . . . . . . . . . . . 14 7. DISPLAY ATTRIBUTES . . . . . . . . . . . . . . 16 8. MEMORY REQUIREMENTS . . . . . . . . . . . . . 16 9. ERROR MESSAGES . . . . . . . . . . . . . . . . 17 10. IMPORTANT NOTES . . . . . . . . . . . . . . . 18 11. APPENDIX . . . . . . . . . . . . . . . . . . . 22 Terms and conditions of use Standard disclaimer Support Demo version restrictions Future enhancements --> Registration and order form <-- ANIDOS - Page 1 1. INTRODUCTION ════════════════ DOS ANIMATOR is a suite of three programs which together allow key depressions to be logged, stored in a script file, and played back to animate any DOS program running in text mode. The script file contains statements in a simple programing language, which are interpreted to control the application. The script file can be edited with any standard ASCII text editor, to simulate key depressions, provide delays, or to display colour "pop-up" texts anywhere on the screen. Interactive statements are also supported, it can display a pop-up menu, then jump to any part of the script according to the key pressed. Conditional jumps can also be made on the contents of any part of the screen, for checking texts displayed by the application. Screen data or any texts can be written or appended to files. Primary uses are for creating demonstrations and tutorials for existing DOS programs, for running scripts to initialize an application, to provide interactive menu-driven "front ends" for DOS applications (even to create Microsoft Windows front ends), or to automate software testing. File ANIDOSxx.ZIP contains these files (xx is the version number, blank for the demonstration version): ANIDOS.DOC This file. ATSR.COM Small resident "kernel", which controls key logging and execution of the script file. ARUN.EXE Loads the application program and runs the script file, simulating key depressions, controlling the timing, and displaying pop-up windows etc. ALOG.EXE Key logger, which creates the initial script file while running the application by logging all key depressions. DEMO.BAT Batch file for running the demonstration script. DEMO.ANI Demonstration script file, execute by running the DEMO batch file. DOS.COM A dummy "do-nothing" application (which is executed by DEMO.BAT). This allows DOS itself to be animated without loading another copy of the COMMAND.COM shell, thus saving memory and the "EXIT" command. See notes in section 10. REBOOT.COM Utility to reboot the computer from a batch file. Effectively removes ATSR.COM from memory. ANIDOS - Page 2 2. INSTALLATION ON A HARD DISK ══════════════════════════════ To install DOS ANIMATOR, create a directory named ANIDOS (or any other suitable name), then unzip the file ANIDOSxx.ZIP into this directory (this requires PKUNZIP). Then run the batch file named "DEMO" (from the ANIDOS directory), which shows you some of DOS ANIMATOR's features. For example: C:\>md anidos C:\>cd anidos C:\ANIDOS>pkunzip a:anidos C:\ANIDOS>demo You may also want to put the directory name into the "PATH" in your AUTOEXEC.BAT file, so you can run DOS ANIMATOR from any other directory (after rebooting). ANIDOS - Page 3 3. OPERATION ════════════ Before DOS ANIMATOR can be used, the resident program ATSR must be loaded, with this command: ATSR bufsize "bufsize" is the buffer size in bytes (maximum 40'000). Each logged key depression requires 2 bytes, so this gives a maximum of up to 20'000 key depressions, excluding any space taken up by delays and pop-up window texts etc. The default is 5'000 bytes (space for up to 2'500 characters). The size of the buffer needed by individual script files is determined by using ARUN with the "/t" switch, see below. Keep this to the minimum, since it reduces the memory available for the application. ATSR will run in high memory, see your memory manager or DOS 5.0+ documentation. Next, the initial script file must be created, either using a standard ASCII text editor, or by using the ALOG program to log key depressions while using the application: ALOG scriptfile program [arguments...] "scriptfile" is the name of the file which will be created to hold the logged key depressions, "program" is the name of the application program to be run, and "arguments..." is a list of command-line arguments required by the application. The application program is executed, and all key depressions are logged and saved in the script file. After creating a script file with ALOG, it should be examined and edited. Delays will need to be added at certain places, and pop-up window texts and other statements can be added. Delays must be added which skip over any points where the application clears the keyboard buffer to prevent type-ahead (which will eat key depressions when they're played back), or to wait for the application to complete a slow operation. Ensure that the delay is long enough to be sufficient when the script is run on slow PCs (e.g. 4.77MHz) with floppy disks. After editing the script file, it should be checked for valid syntax, and the size of buffer determined, by using ARUN with the "/t" (for test) switch: ARUN scriptfile /t Any syntax errors will be displayed, with a caret "^" pointing to (or just after) the suspect character or value. The buffer size can be used when loading the resident ATSR program. ANIDOS - Page 4 If testing shows no errors, the script file can then be played back using ARUN: ARUN scriptfile program [arguments...] Playback can be aborted by pressing "SysReq". The application can then be used as normal from then on. When aborted, the last pop-up window displayed is cleared. Scripts, like most other programs, rarely run the first time. The most common problem is caused by applications clearing the keyboard buffer. See the IMPORTANT NOTES. ARUN returns a value to DOS (which can be checked by using ERRORLEVEL in a batch file): 0 OK 1 ARUN command-line error 2 ATSR not loaded 3 Can't open script file 4 Syntax error in script file 5 Read error on script file 6 Buffer too small 7 Not enough memory to run program 8 Program not found 9 Can't run program ANIDOS - Page 5 4. SCRIPT FILE STATEMENTS ═════════════════════════ The script file contains key strokes, wait statements for timing, pop-up window texts, file output, conditional statements (on key press or screen contents), jumps, gosubs and comments. Any white space, which is not enclosed in quotes, is ignored (spaces, carriage returns, linefeeds and tabs). The script language is simple and concise (to save typing), each command is introduced by a single ASCII character in upper or lower case, for example "j" is for Jump, "p" is for Pop-up window etc. 4.1 Comments ───────────── Comments are preceded by a ";" character. Everything after the ";" to the end of the line is ignored. The first line of a script file created by ALOG is a comment containing the application name and argument list which were used when the log file was created. 4.2 Key strokes ──────────────── Key strokes to be played back are entered in the following ways: - as characters or strings enclosed in single or double quotes e.g. '1' "1" "Hello" '1964' "can't" 'She said "Hi!"' - as decimal ASCII codes e.g. carriage return = 13 - as hexadecimal ASCII codes by preceding the hex value with "$" e.g. carriage return = $0D, escape = $1B - as scan codes in decimal or hex, for function keys and special control keys, these are preceded by "#" if in decimal, or "#$" if in hex e.g. function key F1 = #59 (decimal) or #$3B (hex) Scan codes and ASCII key codes are listed in the key code table in section 6. Key strokes can be removed from the keyboard buffer with the "L" (fLush keyboard buffer) statement. The "E" (Empty) statement waits unitl the keyboard buffer is empty. 4.3 Jump labels ──────────────── Labels are destinations for the "Jump", "Gosub" or conditional statements. Labels can be up to 20 characters long, and can contain the alphanumeric characters A..Z and 0..9, and the underline character '_'. Label definitions are preceded by a colon character ':', label references do not require the colon. :a_label ; Label definitions are preceded by a colon ; (no space allowed between colon and label) :ThisIsALongLabel :1234 ; Numbers can also be used j a_label ; Label reference - jump to label "a_label" ANIDOS - Page 6 4.4 Jumps ────────── The "J" (Jump) statement jumps to a label and continues executing the script from there. J label ; ":label" is the destination, see 4.3 4.5 Gosub and Return ───────────────────── The "G" (Gosub) statement calls a labelled subroutine, and the "R" (Return) statement returns from the subroutine to continue execution from the statement after the gosub. Subroutine calls can be nested up to 8 deep, e.g. subroutines can contain "Gosub" statements. If nesting is deeper than 8, the gosub call is ignored. ... G MySub ; call the subroutine ... ; on return, execution continues from here Q ; end of script :MySub ; start of subroutine ... ; subroutine body, any statements R ; return from subroutine 4.6 Timing and delays ────────────────────── There are two timing statements: - The delay between key depressions on playback can be set with a "Dn" (Delay) statement, where "n" is the number of real- time clock ticks to delay. The delay can be changed at any time, and remains in effect until another delay statement is processed, e.g. D18 = one second. The default is 0.5 second. D1 is about 18 characters per second. Use D0 for no delays between characters, see notes in section 10. - Waits can be entered with the "Wn" (Wait) statement, where "n" is the number of real-time clock ticks to delay. Waits are typically used to pause while the application completes a long operation, to skip over a point where the application clears the keyboard buffer, or to pause to give time for a pop-up text window to be read. e.g. W180 = ten second delay The real-time clock "ticks" every 55 milliseconds. There are 18.2 ticks per second, so "w18" waits for about one second. ANIDOS - Page 7 4.7 Displaying pop-up windows ────────────────────────────── Pop-up windows are introduced with the "P" (Pop-up) statement: P attr column line text line(s)... ; each on a fresh line . ; "." ends the statement attr The display attribute as a decimal or hex number (0-255), e.g. 62 or $3E = yellow text on a cyan background, see the table below. Ignored if mono screen (but must be present anyway). column The column number (0..79) of the top right-hand corner of the window in decimal. line The line number (0..24) of the top right-hand corner of the window in decimal. . Ends the "P" statement, must be on a fresh line A box is automatically drawn around the window. The last pop-up window is cleared with a "C" (Clear) statement. Note that if more than one pop-up window is displayed on the same screen, only the last window can be cleared. For example: p $3e 10 3 ; display a window This is a pop-up window displayed on line 3, column 10, with yellow text on a cyan background. . ; end of window w180 c ; wait 10 seconds, then ; clear the window This displays the box: ╔═════════════════════════════╗ ║ This is a pop-up window ║ ║ displayed on line 3, column ║ ║ 10, with yellow text on a ║ ║ cyan background. ║ ╚═════════════════════════════╝ 4.8 Displaying texts ───────────────────── Texts, without a box drawn around them, are displayed with the "T" (Text) statement, which is similar to the pop-up window statement described above. These are also cleared with the "C" statement. T attr column line text.... ; one or more lines of text . ; "." ends the statement e.g. T 15 5 13 <-- Command line . ANIDOS - Page 8 4.9 Interactive keyboard input (not in demonstration version) ────────────────────────────────────────────────────────────── DOS ANIMATOR can pause and wait for the user to press a key, and can then jump to a label according to which key is pressed, with the "K" (on Key) statement: K key label ... ; key code and label to jump to if key pressed . ; "." ends the statement The key can be an ASCII character enclosed in single or double quotes (not case sensitive) e.g. "k"; a decimal or hex key code e.g. 12, $34; or a decimal or hex scan code e.g. #23, #$45. Each key and associated label should be on a separate line. To accept any key, leave out the key and label lines, use only: K . ; waits for any key to be pressed For example, this script implements a (very) basic DOS menu. If this was in a file called "DOSMENU", it would be executed with the command: "ARUN DOSMENU DOS". :loop d0 t 62 20 3 ╓── VERY BASIC DOS MENU ──┐ ║ D Directory │ ║ V Version │ ║ Q Quit │ ║ F1 Help │ ║ Press D, V, Q or F1. │ ╚═════════════════════════╛ . k 'd' dir ; if 'd' or 'D' pressed, jump to "dir" 'v' ver ; if 'v' or 'V' pressed, jump to "ver" 'q' quit ; if 'q' or 'Q' pressed, jump to "quit" #$3B help ; "F1" = Help . ; . = end of key/label list :dir c 'dir /w' 13 j done ; directory :ver c 'ver' 13 j done ; version :quit 'cls' 13 q ; quit, end the script :help p $1e 15 9 A pop-up help window. Press any key to continue. . k . ; input any key c j loop ; clear pop-up help window, continue :done 0 ; NUL, causes DOS to wait until complete j loop ; re-display the menu ANIDOS - Page 9 4.10 Examining the screen (not in demonstration version) ───────────────────────────────────────────────────────── The "X" (eXamine) statement allows any part of the screen to be examined and compared with one or more strings. A jump is made according to which string matches the data on the screen at the given location. The comparison IS case sensitive. If no string matches, script execution "falls through" and continues from the next statement. Up to 80 strings can be compared in one statement. This feature should be used to determine if certain actions were successfully completed, such as making connection via a modem or opening a file etc. It is normally used to check for the presence of error messages. X column line ; starting column and line "string1" label1 ; first string to compare "string2" label2 ... ; other strings (up to 80 maximum) . ; "." ends the list For example: X 1 23 ; examine line 23 column 1 "ERROR" Error ; if it contains the word "ERROR" ; then jump to label "Error" " " NoError ; else jump to label "NoError" . ; else continue 4.11 Shift, Alt, Ctrl and Lock key states ────────────────────────────────────────── The states of the shift, control, alt, num lock, scroll lock, caps lock and insert keys are controlled by "+k" and "-k" statements, where "k" is a character which determines the key. e.g. +a #30 -a = Alt key down, Alt+A, Alt key up. +n = Num Lock on ┌──────┬─────┬──────────────────┬─────┬─────┬──────────────┐ │ DOWN │ UP │ SHIFT KEYS │ ON │ OFF │ TOGGLE KEYS │ ├──────┼─────┼──────────────────┼─────┼─────┼──────────────┤ │ +R │ -R │ Right Shift key │ +S │ -S │ Scroll Lock │ │ +L │ -L │ Left Shift key │ +N │ -N │ Num Lock │ │ +C │ -C │ Ctrl key │ +K │ -K │ Caps Lock │ │ +X │ -X │ Right Ctrl key │ +I │ -I │ Insert │ │ +A │ -A │ Alt key │ │ │ │ │ +Z │ -Z │ Right Alt key │ │ │ │ └──────┴─────┴──────────────────┴─────┴─────┴──────────────┘ NOTE: These affect only the keyboard status flags, the correct ASCII codes or scan codes must be used to represent Ctrl and Alt characters. For example, don't use "+c 'c' -c" for Ctrl+C, instead use 3 (the ASCII code for Ctrl+C is 3), "+c 3 -c" is also valid and may be required by some applications. ANIDOS - Page 10 4.12 Cursor on/off ────────────────── The cursor can be turned off with the "O" (Off) command, and back on again with the "N" (oN) command. The cursor must be turned off *before* it can be turned on again, because this saves the original cursor shape, which is restored when it is subsequently turned on. 4.13 File commands (not in demonstration version) ────────────────────────────────────────────────── There are three commands for accessing files. "Save" saves screen data to a file, "File" writes a given text to a file, and "Unlink" deletes a file. Files can be used as a simple communication method between an animated DOS program, and a "front-end" Microsoft Windows program. 4.13.1 Save ──────────── The "S" (Save) statement saves a defined section of the screen to a file. It can either create a new file, or append the text to an existing file. The top right-hand corner, and bottom left- hand corner of the area to be saved must be given. This feature is very useful for saving error messages or data that is displayed by an application which cannot save this information in a file, or for saving screens so that they can be compared with the correct screens for automated software testing. It is also useful for storing data which can be processed by another program, for example by a Microsoft Windows "front-end" for an old DOS program, which is being controlled by DOS ANIMATOR. Format: S top_col top_line bot_col bot_line filename [A] top_col top_line Top corner of block to be saved. bot_col bot_line Bottom corner of block to be saved. filename Name of file to save the text in, may be a complete drive/path name. A Optional "Append" flag. If present then the file is assumed to exist, and the text is appended to the end of the file. If not present, then the file is created (any existing file is deleted). "Save" examples: s 0 0 79 24 screen.txt ; Saves the entire screen to ; file "screen.txt" in the ; current directory. s 10 3 20 5 \test\1.txt a ; Appends lines 3..5, columns ; 10..20 to the end of file ; "\test\1.txt". ANIDOS - Page 11 4.13.2 File ──────────── The "F" (File) statement writes or appends a given text to a given file. This can be useful in logging the progress of an application. For example, the "X" (eXamine) statement can check the screen for certain messages, and can write a progress report to a file. Format: F "text" filename [A] text Text to be written to the file. filename Name of the file to save the text in. A Optional "Append" flag. If present then the file is assumed to exist, and the text is appended to the end of the file. If not present, then the file is created (any existing file with the same name is deleted). Example: F "An error occurred" errors.txt ; Writes the string "An error occurred" ; to file "errors.txt" in the current ; directory 4.13.3 Unlink ────────────── The "U" (Unlink) statement deletes a file. Examples: U c:\test\fred.txt ; Deletes file "c:\test\fred.txt" 4.14 Quit, end the script ────────────────────────── The "Q" (Quit) statement can be placed anywhere in the script, and terminates script execution. The application can be used as normal from this point. Example: :EndScript q ; Jump to EndScript to quit script ANIDOS - Page 12 5. SCRIPT LANGUAGE SUMMARY ══════════════════════════ "ASCII keys" or 'ASCII keys' ; E.g. "CAN'T" or '"HELLO"' ; comment ; Ignored, allowed anywhere in script file P attr column line ; Display pop-up window window text... . ; "." ends the statement T attr column line ; Display text text lines... . ; "." ends the statement C ; Close pop-up or text window Dn ; Set default delay between keys ; to "n" ticks (D0 = no delay) ; e.g. D10 = 10 x 55mS = 0.55S Wn ; Wait "n" ticks ; e.g. W180 = 180 x 55mS = 10S #n ; Decimal scan code ; e.g. #81 = PgDn #$n ; Hex scan code ; e.g. #$51 = PgDn n ; Decimal ASCII character ; e.g. 13 = carriage return $n ; Hex ASCII character ; e.g. $0D = carriage return :label ; Label definition J label ; Jump to "label" G label ; Gosub, call subroutine "label" R ; Return, return from subroutine K ; On Key key1 label1 ; if "key", jump to "label" key2 label2.... ; can contain many keys... . ; "." ends the statement X column line ; Examine the screen, if it "string1" label1 ; contains "string" jump to "label", "string2" label2 ... ; can compare up to 80 strings, . ; "." ends the statement E ; Wait until keyboard buffer is empty L ; fLushes (clears) the keyboard buffer O ; Turn Off the cursor N ; Turn oN the cursor ; Save screen data to a file S top_col top_lin bot_col bot_lin filename [A] F "text" [A] ; FIle, write text to a file U ; Unlink (delete) a file Q ; Quit, end script execution ANIDOS - Page 13 Shift keys (+ down, - up): Toggle keys (+ on, - off): +R -R ; Right Shift key +S -S ; Scroll Lock +L -L ; Left Shift key +N -N ; Num Lock +C -C ; Ctrl key +K -K ; Caps Lock +X -X ; Right Ctrl key +I -I ; Insert +A -A ; Alt key +Z -Z ; Right Alt key ANIDOS - Page 14 6. KEY CODE TABLE ═════════════════ ┌──────┬────────┬────────────┬────────────┬────────────┬────────────┐ │ │ SCAN │ ASCII │ SHIFT │ CTRL │ ALT │ │ │ CODE │ │ │ │ │ │ Key │ Dec Hex│ Dec Hex Chr│ Dec Hex Chr│ Dec Hex Chr│ Dec Hex Chr│ ╞══════╪════════╪════════════╪════════════╪════════════╪════════════╡ │ ESC │ 1 01 │ 27 1B ESC│ 27 1B ESC│ 27 1B │ │ │ 1 ! │ 2 02 │ 49 31 1 │ 33 21 ! │ │ 120 78 NUL│ │ 2 @ │ 3 03 │ 50 32 2 │ 64 40 @ │ 3 03 NUL│ 121 79 NUL│ │ 3 # │ 4 04 │ 51 33 3 │ 35 23 # │ │ 122 7A NUL│ │ 4 $ │ 5 05 │ 52 34 4 │ 36 24 $ │ │ 123 7B NUL│ │ 5 % │ 6 06 │ 53 35 5 │ 37 25 % │ │ 124 7C NUL│ │ 6 ^ │ 7 07 │ 54 36 6 │ 94 5E ^ │ 30 1E │ 125 7D NUL│ │ 7 & │ 8 08 │ 55 37 7 │ 38 26 & │ │ 126 7E NUL│ │ 8 * │ 9 09 │ 56 38 8 │ 42 2A * │ │ 127 7F NUL│ │ 9 ( │ 10 0A │ 57 39 9 │ 40 28 ( │ │ 128 80 NUL│ │ 0 ) │ 11 0B │ 48 30 0 │ 41 29 ) │ │ 129 81 NUL│ │ - _ │ 12 0C │ 45 2D - │ 95 5F _ │ 31 1F │ 130 82 NUL│ │ = + │ 13 0D │ 61 3D = │ 43 2B + │ │ 131 83 NUL│ │ BKSP │ 14 0E │ 8 08 │ 8 08 │ 127 7F │ │ │ TAB │ 15 0F │ 9 09 │ 15 0F NUL│ │ │ │ Q │ 16 10 │ 113 71 q │ 81 51 Q │ 17 11 │ 16 10 NUL│ │ W │ 17 11 │ 119 77 w │ 87 57 W │ 23 17 │ 17 11 NUL│ │ E │ 18 12 │ 101 65 e │ 69 45 E │ 5 05 │ 18 12 NUL│ │ R │ 19 13 │ 114 72 r │ 82 52 R │ 18 12 │ 19 13 NUL│ │ T │ 20 14 │ 116 74 t │ 84 54 T │ 20 14 │ 20 14 NUL│ │ Y │ 21 15 │ 121 79 y │ 89 59 Y │ 25 19 │ 21 15 NUL│ │ U │ 22 16 │ 117 75 u │ 85 55 U │ 21 15 │ 22 16 NUL│ │ I │ 23 17 │ 105 69 i │ 73 49 I │ 9 09 │ 23 17 NUL│ │ O │ 24 18 │ 111 6F o │ 79 4F O │ 15 0F │ 24 18 NUL│ │ P │ 25 19 │ 112 70 p │ 80 50 P │ 16 10 │ 25 19 NUL│ │ [ { │ 26 1A │ 91 5B [ │ 123 7B { │ 27 1B ESC│ │ │ ] } │ 27 1B │ 93 5D ] │ 125 7D } │ 29 1D │ │ │ Enter│ 28 1C │ 13 0D CR │ 13 0D CR │ 10 0A LF │ │ │ Ctrl │ 29 1D │ │ │ │ │ │ A │ 30 1E │ 97 61 a │ 65 41 A │ 1 01 │ 30 1E NUL│ │ S │ 31 1F │ 115 73 s │ 83 53 S │ 19 13 │ 31 1F NUL│ │ D │ 32 20 │ 100 64 d │ 68 44 D │ 4 04 │ 32 20 NUL│ │ F │ 33 21 │ 102 66 f │ 70 46 F │ 6 06 │ 33 21 NUL│ │ G │ 34 22 │ 103 67 g │ 71 47 G │ 7 07 │ 34 22 NUL│ │ H │ 35 23 │ 104 68 h │ 72 48 H │ 8 08 │ 35 23 NUL│ │ J │ 36 24 │ 106 6A i │ 74 4A I │ 10 0A │ 36 24 NUL│ │ K │ 37 25 │ 107 6B j │ 75 4B J │ 11 0B │ 37 25 NUL│ │ L │ 38 26 │ 108 6C k │ 76 4C K │ 12 0C │ 38 26 NUL│ │ ; : │ 39 27 │ 59 3B ; │ 58 3A : │ │ │ │ ' " │ 40 28 │ 39 27 ' │ 34 22 " │ │ │ │ ` ~ │ 41 29 │ 96 60 ` │ 126 7E ~ │ │ │ └──────┴────────┴────────────┴────────────┴────────────┴────────────┘ NOTE: The Dec and Hex numbers for keys which have NUL in the "Chr" column are SCAN CODES. Scan codes are put into the script file with #nn (decimal) or #$nn (hex). ANIDOS - Page 15 ┌──────┬────────┬────────────┬────────────┬────────────┬────────────┐ │ │ SCAN │ ASCII │ SHIFT │ CTRL │ ALT │ │ │ CODE │ │ │ │ │ │ Key │ Dec Hex│ Dec Hex Chr│ Dec Hex Chr│ Dec Hex Chr│ Dec Hex Chr│ ╞══════╪════════╪════════════╪════════════╪════════════╪════════════╡ │LShift│ 42 2A │ │ │ │ │ │ \ | │ 43 2B │ 92 5C \ │ 124 7C | │ 28 1C │ │ │ Z │ 44 2C │ 122 7A z │ 90 5A Z │ 26 1A │ 44 2C NUL│ │ X │ 45 2D │ 120 78 x │ 88 58 X │ 24 18 │ 45 2D NUL│ │ C │ 46 2E │ 99 63 c │ 67 43 C │ 3 03 │ 46 2E NUL│ │ V │ 47 2F │ 118 76 v │ 86 56 V │ 22 16 │ 47 2F NUL│ │ B │ 48 30 │ 98 62 b │ 66 42 B │ 2 02 │ 48 30 NUL│ │ N │ 49 31 │ 110 6E n │ 78 4E N │ 14 0E │ 49 31 NUL│ │ M │ 50 32 │ 109 6D m │ 77 4D M │ 13 0D │ 50 32 NUL│ │ , < │ 51 33 │ 44 2C , │ 60 3C < │ │ │ │ . > │ 52 34 │ 46 2E . │ 62 3E > │ │ │ │ / ? │ 53 35 │ 47 2F / │ 63 3F ? │ │ │ │RShift│ 54 36 │ │ │ │ │ │*PrtSc│ 55 37 │ 42 2A * │ INT5│ │ │ │ Alt │ 56 38 │ │ │ │ │ │ Space│ 57 39 │ 32 20 │ 32 20 │ 32 20 │ 32 20 │ │ Caps │ 58 3A │ │ │ │ │ │ F1 │ 59 3B │ 59 3B NUL│ 84 54 NUL│ 94 5E NUL│ 104 NUL│ │ F2 │ 60 3C │ 60 3C NUL│ 85 55 NUL│ 95 5F NUL│ 105 NUL│ │ F3 │ 61 3D │ 61 3D NUL│ 86 56 NUL│ 96 60 NUL│ 106 NUL│ │ F4 │ 62 3E │ 62 3E NUL│ 87 57 NUL│ 97 61 NUL│ 107 NUL│ │ F5 │ 63 3F │ 63 3F NUL│ 88 58 NUL│ 98 62 NUL│ 108 NUL│ │ F6 │ 64 40 │ 64 40 NUL│ 89 59 NUL│ 99 63 NUL│ 109 NUL│ │ F7 │ 65 41 │ 65 41 NUL│ 90 5A NUL│ 100 64 NUL│ 110 NUL│ │ F8 │ 66 42 │ 66 42 NUL│ 91 5B NUL│ 101 65 NUL│ 111 NUL│ │ F9 │ 67 43 │ 67 43 NUL│ 92 5C NUL│ 102 66 NUL│ 112 NUL│ │ F10 │ 68 44 │ 68 44 NUL│ 93 5D NUL│ 103 67 NUL│ 113 NUL│ │ Num │ 69 45 │ │ │ │ │ │Scroll│ 70 46 │ │ │ │ │ │ Home │ 71 47 │ 71 47 NUL│ 55 37 7 │ 119 77 NUL│ │ │ Up │ 72 48 │ 72 48 NUL│ 56 38 8 │ │ │ │ PgUp │ 73 49 │ 73 49 NUL│ 57 39 9 │ 132 84 NUL│ │ │Grey -│ 74 4A │ 45 2D - │ 45 2D - │ │ │ │ Left │ 75 4B │ 75 4B NUL│ 52 34 4 │ 115 73 NUL│ │ │Center│ 76 4C │ │ 53 35 5 │ │ │ │ Right│ 77 4D │ 77 4D NUL│ 54 36 6 │ 116 74 NUL│ │ │Grey +│ 78 4E │ 43 2B + │ 43 2B + │ │ │ │ End │ 79 4F │ 79 4F NUL│ 49 31 1 │ 117 75 NUL│ │ │ Down │ 80 50 │ 80 50 NUL│ 50 32 2 │ │ │ │ PgDn │ 81 51 │ 81 51 NUL│ 51 33 3 │ 118 76 NUL│ │ │ Ins │ 82 52 │ 82 52 NUL│ 48 30 0 │ │ │ │ Del │ 83 53 │ 83 53 NUL│ 46 2E . │ │ │ └──────┴────────┴────────────┴────────────┴────────────┴────────────┘ NOTE: The Dec and Hex numbers for keys which have NUL in the "Chr" column are SCAN CODES. Scan codes are put into the script file with #nn (decimal) or #$nn (hex). ANIDOS - Page 16 7. DISPLAY ATTRIBUTES ═════════════════════ The attribute is a one-byte value, where the most significant 3 bits (6..4) define the background colour, and the least significant 4 bits (3..0) define the foreground (text) colour, bit 7 controls blinking. These are the values in hex: Background colours Foreground colours (1st hex digit) (2nd hex digit) ────────────────── ────────────────── Black 0 Black 0 Blue 1 Blue 1 Green 2 Green 2 Cyan 3 Cyan 3 Red 4 Red 4 Magenta 5 Magenta 5 Brown 6 Brown 6 White 7 White 7 Dark grey 8 Light blue 9 Light green A Light cyan B Light red C Light magenta D Yellow E White F For example, a cyan background with yellow foreground text is $3E hex (62 decimal). To make the foreground blink, add 80 hex (128 decimal) to the value, e.g. $0F = white foreground, black background $8F = blinking white foreground, black background 8. MEMORY REQUIREMENTS ══════════════════════ The resident kernel (ATSR) uses about 7000 bytes + buffer size. The buffer size is defined when ATSR is loaded, using the command: ATSR bufsize (not demonstration version). ALOG remains resident in memory while running the application to log key depressions. This uses just over 20K bytes. ARUN is *not* resident in memory when the application runs, and does not reduce the amount of memory available to the application. If the application gives an "out of memory" error: - Ensure that ATSR's buffer is not larger than necessary. Use the buffer size shown by using the command: ARUN scriptfile /T - Remove any unnecessary memory-resident programs, TSRs, and device drivers, such as RAM disks, disk caches, DOS shells etc. ANIDOS - Page 17 9. ERROR MESSAGES ═════════════════ <n> syntax error(s) in script file: <filename> ARUN displays all script file lines which contain syntax errors. The line number of the invalid line is displayed, followed by the line itself, with a caret ^ pointing to (or just after) the invalid character. A ">" character is shown if the error location is beyond column 80. If any errors are found, the script file will not be run. ATSR not loaded Run program ATSR.COM to install the memory resident section of the program before running ALOG or ARUN. Can't open file: <filename> a) Trying to read the script file - the file doesn't exist in the current or given directory. b) Trying to write the script file - the disk is full or not ready. c) Trying to run the application - the application is not in the current directory, or is not in the PATH, or is a batch file (.BAT). Batch files cannot be run directly by ARUN, see notes in section 10. Read error on file: <filename> Corrupted application or script file. Exec file format error: <filename> The file is not an ".EXE" or ".COM" format file. Not enough memory to run program: <filename> More memory can be obtained by removing other memory-resident programs such as disk caches, RAM disks, DOS shells etc. The ATSR buffer size can also be reduced to a minimum (use the buffer size shown by running ARUN with the "/t" switch). Buffer size too small The size of the buffer set when ATSR was loaded is too small. Reboot the machine with Ctrl+Alt+Del, then execute ATSR bufsize, where "bufsize" is the buffer size required by the script you want to run. <line>: Out of label space DOS ANIMATOR allows a maximum of 100 label definitions, and 200 label references in a single script file. <line>: Multi-defined label: <label> The <label> is defined more than once in the script file. Undefined label: <label> The label has been referenced but is not defined. ANIDOS - Page 18 10. IMPORTANT NOTES ═══════════════════ OPERATING SYSTEMS AND MICROSOFT WINDOWS: DOS ANIMATOR runs under DOS versions 3 to 6, in text mode only. It has not been tested with Digital Research DOS (DRDOS), but should run OK. It runs under Microsoft Windows 3, ATSR can be loaded before running Windows, or can be loaded from the MS-DOS window prompt (but is unloaded when MS-DOS is exited). IF THE SCRIPT FILE WON'T RUN CORRECLTY: This is nearly always caused by invalid code in the script file. Ensure that you have inserted sufficient delays with the "W" wait command for your application to have finished processing before further key depressions are supplied. Some applications clear the keyboard buffer after every action, you *must* delay script execution until after this point, otherwise keys will be lost. ALOG and ARUN cannot run batch files (.BAT) directly (e.g. DW4), see note below. Some programs which don't chain interrupt handlers correctly, or which switch the video "page" may not run properly. SCRIPTS TO INITIALIZE AN APPLICATION: If all the script file statements are processed (or the script contains the "q" quit statement), and the application is still running, the application can then be used as normal. This allows script files to be written to automatically carry out any init- ialization operations which would otherwise have to be repeated every time the application was run. To make initialization scripts run as fast as possible, set the delay between keys to the minimum, with a "d0" statement at the start of the script. CREATING LARGE SCRIPT FILES: When creating script files, it is better to produce many small script files, which can be individually tested, then merged into the final file. Use ALOG to produce several script files, then edit and test each one individually. When each is fully tested, remove the unwanted intro and exit scripts then merge them together and run a final complete test. You can also insert "j" jump statements to jump from the start of a script to the part which is being tested, or to jump around untested parts. ANIDOS - Page 19 WAIT STATEMENTS AND PLAYBACK TIMING: When introducing delays with the "w" wait statement, remember that the application will run faster on some machines than on others. Ensure that any delays are adequate for the slowest machine that the package will be run on, e.g. a 4.77MHz PC with floppy disks. If you're using a disk cache, remember that an application will take much longer to load when it is first used, because it's loaded from the disk the first time, and thereafter it's loaded from cache RAM. DOS ANIMATOR's delays will always be the same on every machine, because the machine's real-time clock is used for timing. EXECUTING BATCH (.BAT) FILES WITH ARUN: The application must be a ".EXE" or ".COM" file. ALOG and ARUN cannot execute batch files directly. This is because the DOS command line interpretor (COMMAND.COM) is required to execute a batch file, and COMMAND.COM must be run as if it is the app- lication. To do this, use "ARUN <scriptfile> DOS", and put the key depressions to execute the batch file into the script file. To create a log file, use "ALOG <scriptfile> COMMAND" (run COMMAND.COM as the application), then type the keys to run the batch file. For example, if the script file was named SCRIPT and the batch file was named BATCH, then type these commands to create a log file. Use the DOS "EXIT" command to end. C:\>ALOG SCRIPT COMMAND Executes COMMAND.COM .... the DOS shell signs on C:\>BATCH Run the batch file .... C:\>EXIT Exits DOS shell, saves the SCRIPT file To run the SCRIPT file, use: C:\>ARUN SCRIPT COMMAND Loads COMMAND.COM which will run the batch file Alternatively, you can use the dummy DOS shell called DOS.COM. If you do this, you can delete the "EXIT" command from the end of the script: C:\>ARUN SCRIPT DOS DOS.COM contains only a "return" instruction, which returns immediately to the existing COMMAND.COM shell, which processes further key depressions. DOS.COM *cannot* be used to create script files using ALOG (e.g. ALOG SCRIPT DOS) because there is no way to "exit" and save the script file, since DOS.COM exits immediately and creates an empty script file. ANIDOS - Page 20 AWAITING COMPLETION OF DOS COMMANDS WHEN ANIMATING DOS: When animating DOS itself using "ARUN x DOS" or "ARUN x COMMAND", the script can be paused until the DOS command or application has been completed and the DOS prompt has been displayed, by putting a NUL character (0) in the script. DOS ignores this character, but does not continue until it has been read from the keyboard buffer. See the example in section 4.9. DELETING UNWANTED FILES CREATED BY THE APPLICATION: If files are created by the application when the script file is run, these may need to be deleted afterwards. The "U" (Unlink) statement can be used to delete these files before ending the script. Alternatively, the ARUN command can be executed from a batch file which can then clean up or delete such files. For example: echo off arun script myprog test.tmp del test.tmp CLEARING POP-UP WINDOWS AND TEXTS: Ensure that any pop-up windows or texts displayed by the script are cleared with the "c" statement before the application scrolls the screen. DOS ANIMATOR doesn't keep track of window positions if the screen is scrolled, and will restore the background to the wrong position on the screen when a "c" statement executes. IF ALOG CREATES AN EMPTY SCRIPT FILE: ALOG cannot create a script file with some programs. This is because these programs steal the same interrupts as ALOG, and do not chain the interrupts correctly, thus preventing ALOG seeing any key depressions. However, manually created script files will work perfectly. SYNCHRONIZATION BETWEEN DOS ANIMATOR AND THE APPLICATION: Before any actions are executed (displaying a pop-up window, changing the state of the shift, alt, ctrl, insert, or lock keys, inputting a key from the user or examining the screen), DOS ANIMATOR waits until all the preceding keys have been processed, thus ensuring that all actions are synchronized. SHIFT, CTRL AND ALT KEY STATES: The "+k" and "-k" statements (section 4.11) affect only the keyboard status flags. The correct ASCII codes or scan codes should be used to represent Ctrl and Alt characters. For example, don't use "+c 'c' -c" for Ctrl+C, instead use 3 (the ASCII code for Ctrl+C is 3), "+c 3 -c" is also valid and may be required by some applications. ANIDOS - Page 21 CTRL+C AND CTRL+BREAK: DOS ANIMATOR does not disable the Ctrl+Break interrupt handler, and does not prevent the keyboard buffer being emptied by DOS. This is because Ctrl+Break or Ctrl+C may be needed in the script file. Some applications exit when Ctrl+C or Ctrl+Break is pressed, and the keyboard buffer is always emptied by DOS, so these key combinations should *not* be pressed while the script is executing. PRESSING CTRL, ALT OR SHIFT WHILE RUNNING THE SCRIPT: On certain less well-behaved applications, pressing Ctrl, Alt, Shift or any of the Lock keys may affect execution of the script. DOS ANIMATOR does not disable these keys. ANIDOS - Page 22 11. APPENDIX ════════════ Terms and conditions of use ─────────────────────────── You are free to pass copies of the DEMONSTRATION version (ANIDOS.ZIP) to others, providing it is supplied in its original unmodified form, and no fee is charged for the software. Registered users are free to distribute ATSR.COM, ARUN.EXE and DOS.COM to their customers or sales outlets as part of their own packages. Other files may *not* be distributed unless the receiver registers the package with the author. Unregistered use of the package is very naughty, deprives the author of his livelihood, makes it harder for him to pay the mortgage, feed the cat, and continue to provide a service for Britain's flagging industry. So please register your copy now! Standard disclaimer ─────────────────── Neither the author nor the distributors of this software make any representations regarding the use, the results of use, the correctness, accuracy, reliability or fitness of this software for any particular purpose, and accept no responsibility for its use or misuse. However, if problems are reported by a registered user, every effort will be made to supply a corrected version as soon as possible. Support ─────── Registered users (or potential registered users) can mail me on CompuServe (100015,2546) or CIX (harvey) if they have any questions or problems. Demo version restrictions ───────────────────────── The buffer size is fixed at 5000 bytes. It does not support the "K" (Keyboard), "X" (eXmaine), "S" (Save), "F" (file) or "U" (Unlink) statements. ANIDOS - Page 23 Future enhacements ────────────────── An updated version of this software may be produced if anyone's interested. These features are being considered: - Unloadable version of ATSR. - Script buffer in extended memory. - Keys to pause/continue script execution. - "Hot key" handling ("h" statement), so that truly embedded macro commands can be added to any existing application. Hitting a hot key executes a subroutine in the script, a script file can contain many "hot key" subroutines. - Additions for animating software testing, such as comparing actual and expected screens or sections of screens, and logging the differences to a file. - Include file statement ("i"), so other script files can be included in a main script, e.g. "i fred.ani". - Log to/playback from serial port, for remote monitoring and control. - Sound effects, speech, beeps etc. - Compiler to create binary script files. Further (polite) suggestions welcome. DOS ANIMATOR V1.2 REGISTRATION AND ORDER FORM ═════════════════════════════════════════════ (If on CompuServe, use the "Shareware Registration" service). Name: ___________________________________________________ Position: ___________________________________________________ Company: ___________________________________________________ Address: ___________________________________________________ Town/City: ___________________________________________________ County/State: ______________________ Postcode/Zip: ____________ Country: ___________________________________________________ Telephone: _________________________________________ Disk Size: 3.5" (720K) ____ 5.25" (360K) ____ 5.25" (1.44Mb) ____ Please post me the latest complete version of DOS ANIMATOR. I enclose a registration fee of £25 (includes VAT & P+P) or $35. (Cheques in £s, or US $ money orders, made payable to M.G.Harvey). Signed: _____________________________ Mail the completed form with the registration fee to: Matt Harvey Freelance Development Engineer Studio 9 North Street Dorking Surrey RH4 1DN England VAT No: 515 2859 42 CIX UK: harvey CompuServe: 100015,2546